IRIX Base Documentation 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / ftn / mp.z / mp

Wrap

Text File | 2002-10-03 | 24.0 KB | 415 lines

MP(3F) Last changed: 1-25-99 NNAAMMEE MMPP__BBAARRRRIIEERR, MMPP__BBLLOOCCKK, MMPP__BBLLOOCCKKTTIIMMEE, MMPP__CCRREEAATTEE, MMPP__DDEESSTTRROOYY, MMPP__IINN__DDOOAACCRROOSSSS__LLOOOOPP, MMPP__IISS__MMAASSTTEERR, MMPP__MMYY__TTHHRREEAADDNNUUMM, MMPP__NNUUMMTTHHRREEAADDSS, MMPP__SSEETT__NNUUMMTTHHRREEAADDSS, MMPP__SSEETT__SSLLAAVVEE__SSTTAACCKKSSIIZZEE MMPP__SSEETTLLOOCCKK, MMPP__SSEETTUUPP, MMPP__SSUUGGGGEESSTTEEDD__NNUUMMTTHHRREEAADDSS, MMPP__UUNNBBLLOOCCKK, MMPP__UUNNSSEETTLLOOCCKK, MMPP__SSHHMMEEMM__GGEETT3322, MMPP__SSHHMMEEMM__PPUUTT3322, MMPP__SSHHMMEEMM__IIGGEETT3322, MMPP__SSHHMMEEMM__IIPPUUTT3322, MMPP__SSHHMMEEMM__GGEETT6644, MMPP__SSHHMMEEMM__PPUUTT6644, MMPP__SSHHMMEEMM__IIGGEETT6644, MMPP__SSHHMMEEMM__IIPPUUTT6644 - Fortran multiprocessing utility routines SSYYNNOOPPSSIISS SSUUBBRROOUUTTIINNEE MMPP__BBLLOOCCKK(()) SSUUBBRROOUUTTIINNEE MMPP__UUNNBBLLOOCCKK(()) SSUUBBRROOUUTTIINNEE MMPP__BBLLOOCCKKTTIIMMEE((_i_t_e_r_s)) IINNTTEEGGEERR _i_t_e_r_s SSUUBBRROOUUTTIINNEE MMPP__SSEETTUUPP(()) SSUUBBRROOUUTTIINNEE MMPP__CCRREEAATTEE((_n_u_m) IINNTTEEGGEERR _n_u_m SSUUBBRROOUUTTIINNEE MMPP__DDEESSTTRROOYY(()) IINNTTEEGGEERR FFUUNNCCTTIIOONN MMPP__NNUUMMTTHHRREEAADDSS(()) SSUUBBRROOUUTTIINNEE MMPP__SSEETT__NNUUMMTTHHRREEAADDSS((_n_u_m)) IINNTTEEGGEERR _n_u_m IINNTTEEGGEERR FFUUNNCCTTIIOONN MMPP__MMYY__TTHHRREEAADDNNUUMM(()) IINNTTEEGGEERR FFUUNNCCTTIIOONN MMPP__IISS__MMAASSTTEERR(()) SSUUBBRROOUUTTIINNEE MMPP__SSEETTLLOOCCKK(()) IINNTTEEGGEERR FFUUNNCCTTIIOONN MMPP__SSUUGGGGEESSTTEEDD__NNUUMMTTHHRREEAADDSS((_n_u_m)) IINNTTEEGGEERR _n_u_m SSUUBBRROOUUTTIINNEE MMPP__UUNNSSEETTLLOOCCKK(()) SSUUBBRROOUUTTIINNEE MMPP__BBAARRRRIIEERR(()) LLOOGGIICCAALL FFUUNNCCTTIIOONN MMPP__IINN__DDOOAACCRROOSSSS__LLOOOOPP(()) SSUUBBRROOUUTTIINNEE MMPP__SSEETT__SSLLAAVVEE__SSTTAACCKKSSIIZZEE((_s_i_z_e)) IINNTTEEGGEERR _s_i_z_e MMPP__SSHHMMEEMM__GGEETT3322 (_t_a_r_g_e_t,, _s_o_u_r_c_e,, _l_e_n_g_t_h,, _s_o_u_r_c_e__t_h_r_e_a_d)) MMPP__SSHHMMEEMM__PPUUTT3322 ((_t_a_r_g_e_t,, _s_o_u_r_c_e,, _l_e_n_g_t_h,, _t_a_r_g_e_t__t_h_r_e_a_d)) MMPP__SSHHMMEEMM__IIGGEETT3322 ((_t_a_r_g_e_t,, _s_o_u_r_c_e,, _t_a_r_g_e_t__i_n_c,, _s_o_u_r_c_e__i_n_c,, _l_e_n_g_t_h,, _s_o_u_r_c_e__t_h_r_e_a_d)) MMPP__SSHHMMEEMM__IIPPUUTT3322 ((_t_a_r_g_e_t,, _s_o_u_r_c_e,, _t_a_r_g_e_t__i_n_c,, _s_o_u_r_c_e__i_n_c,, _l_e_n_g_t_h,, _t_a_r_g_e_t__t_h_r_e_a_d)) MMPP__SSHHMMEEMM__GGEETT6644 ((_t_a_r_g_e_t,, _s_o_u_r_c_e,, _l_e_n_g_t_h,, _s_o_u_r_c_e__t_h_r_e_a_d)) MMPP__SSHHMMEEMM__PPUUTT6644 ((_t_a_r_g_e_t,, _s_o_u_r_c_e,, _l_e_n_g_t_h,, _t_a_r_g_e_t__t_h_r_e_a_d)) MMPP__SSHHMMEEMM__IIGGEETT6644 ((_t_a_r_g_e_t,, _s_o_u_r_c_e,, _t_a_r_g_e_t__i_n_c,, _s_o_u_r_c_e__i_n_c,, _l_e_n_g_t_h,, _s_o_u_r_c_e__t_h_r_e_a_d)) MMPP__SSHHMMEEMM__IIPPUUTT6644 ((_t_a_r_g_e_t,, _s_o_u_r_c_e,, _t_a_r_g_e_t__i_n_c,, _s_o_u_r_c_e__i_n_c,, _l_e_n_g_t_h,, _t_a_r_g_e_t__t_h_r_e_a_d)) IIMMPPLLEEMMEENNTTAATTIIOONN IRIX systems DDEESSCCRRIIPPTTIIOONN The multiprocessing routines help control the level of parallelism used in Fortran programs. They should not be needed by most programs, but they can help to tune some applications. These routines are as follows: * MMPP__BBLLOOCCKK uses the bblloocckkpprroocc(2) system call to put all slave threads to sleep. This frees the processors for use by other jobs. This routine is useful if it is known that the slaves will not be needed for some time and the machine is being shared by several users. Calls to MMPP__BBLLOOCCKK cannot be nested; a warning is issued if an attempt to do so is made. * MMPP__UUNNBBLLOOCCKK wakes up slave threads that were previously blocked by a call to MMPP__BBLLOOCCKK. You cannot unblock threads that are not currently blocked; a warning is issued if an attempt is made to do so. It is not necessary to call MMPP__UUNNBBLLOOCCKK explicitly. When a Fortran parallel region is entered, a check is made, and if the slaves are currently blocked, a call is made to MMPP__UUNNBBLLOOCCKK automatically. * MMPP__BBLLOOCCKKTTIIMMEE controls the amount of time a slave thread waits for work before giving up. When enough time has elapsed, the slave thread blocks itself. This automatic blocking is independent of the user-level blocking provided by the MMPP__BBLLOOCCKK and MMPP__UUNNBBLLOOCCkk calls. Slave threads that have blocked themselves are unblocked automatically upon entering a parallel region. The _i_t_e_r_s argument to MMPP__BBLLOOCCKKTTIIMMEE specifies the number of times to spin in the wait loop. By default, it is set to 10,000,000. This takes about .25 seconds on a 200MHz processor. As a special case, an argument of 00 disables the automatic blocking, which allows the slaves to spin-wait without limit. The environment variable MMPP__BBLLOOCCKKTTIIMMEE can be set to an integer value. It acts like an implicit call to MMPP__BBLLOOCCKKTTIIMMEE during program startup. For more information on the MMPP__BBLLOOCCKKTTIIMMEE environment variable, see ppee__eennvviirroonn(5). * MMPP__DDEESSTTRROOYY deletes the slave threads. They are stopped by forcing them to call the eexxiitt(2) system call. In general, doing this is discouraged. MMPP__BBLLOOCCkk can be used in most cases. * MMPP__CCRREEAATTEE creates and initializes threads. Its _n_u_m argument specifies the number of threads to create. Because the calling thread already counts as one, MMPP__CCRREEAATTEE actually creates _n_u_m - 1 new slave threads. * MMPP__SSEETTUUPP creates and initializes threads. It calls MMPP__CCRREEAATTEE using the current default number of threads. Unless otherwise specified, the default number is equal to the number of CPUs currently on the machine, or 8, whichever is less. If you have not called either of the thread creation routines already, then MMPP__SSEETTUUPP is invoked automatically when the first parallel region is entered. If the MMPP__SSEETTUUPP environment variable is set, then the MMPP__SSEETTUUPP routine is called during Fortran initialization, before any user code is executed. * MMPP__NNUUMMTTHHRREEAADDSS returns the number of threads that would participate in an immediately following parallel region. If the threads have already been created, it returns the current number of threads. If the threads have not been created, it returns the current default number of threads. The count includes the master thread. Knowing this count can be useful in optimizing certain kinds of parallel loops by hand, but this function has the side effect of freezing the number of threads to the returned value. As a result, this routine should be used sparingly. To determine the number of threads without this side effect, see the description for the MMPP__SSUUGGGGEESSTTEEDD__NNUUMMTTHHRREEAADDSS routine on this man page. * MMPP__SSEETT__NNUUMMTTHHRREEAADDSS sets the current default number of threads to the specified value. Note that this call does not directly create the threads; it only specifies the number that a subsequent MMPP__SSEETTUUPP call should use. If the MMPP__SSEETT__NNUUMMTTHHRREEAADDSS environment variable is set, it acts like an implicit call to MMPP__SSEETT__NNUUMMTTHHRREEAADDSS during program startup. For more information on the MMPP__SSEETT__NNUUMMTTHHRREEAADDSS environment variable, see the ppee__eennvviirroonn(5) man page. For convenience when operating among several machines with different numbers of CPUs, the _n_u_m argument to MMPP__SSEETT__NNUUMMTTHHRREEAADDSS can be set to an expression involving integer literals; the binary operators ++ or --; the binary functions mmiinn and mmaaxx; and the special symbolic value aallll. The aallll specification requests the total number of available CPUs on the current machine. For example, the following simple specification sets the number of threads to 7, which may be a fine choice on an 8 CPU machine, but would be a very bad choice on a 4 CPU machine: setenv MP_SET_NUMTHREADS 7 A better specification would be the following, which sets the number of threads to be one less than the number of CPUs on the current machine (but always at least one): setenv MP_SET_NUMTHREADS "max(1,all-1)" If your configuration includes some machines with large numbers of CPUs, setting an upper bound is a good idea. A specification such as the following requests no more than 4 cpus: setenv MP_SET_NUMTHREADS "min(all,4)" For compatibility with earlier releases, NNUUMM__TTHHRREEAADDSS is supported as a synonym for MMPP__SSEETT__NNUUMMTTHHRREEAADDSS. * MMPP__MMYY__TTHHRREEAADDNNUUMM returns an integer between 00 and _n - 1, where _n is the value returned by MMPP__NNUUMMTTHHRREEAADDSS. The master process is always thread 0. This routine is occasionally useful for optimizing certain kinds of loops by hand. * MMPP__IISS__MMAASSTTEERR returns 1 if called by the master process, 0 otherwise. * MMPP__SSEETTLLOOCCKK provides convenient (though limited) access to the locking routines. The convenience is that no set up need be done; it may be called directly without any preliminaries. The limitation is that there is only one lock. It is analogous to the uusssseettlloocckk(3P) routine, but it accepts no arguments and does not return a value. This is useful for serializing access to shared variables (for example, counters) in a parallel region. Note that it will frequently be necessary to declare those variables as VVOOLLAATTIILLEE to ensure that the optimizer does not assign them to a register. For information on the VVOOLLAATTIILLEE statement, see your compiler's reference manual. * MMPP__SSUUGGGGEESSTTEEDD__NNUUMMTTHHRREEAADDSS uses its _n_u_m argument as a hint about how many threads to use in subsequent parallel regions. It returns the previous value of the number of threads to be employed in parallel regions. It does not affect currently executing parallel regions, if any. The implementation may ignore this hint depending on factors such as overall system load. This routine can also be called with _n_u_m = 0, in which case it simply returns the number of threads to be employed in parallel regions without the side effect present in MMPP__NNUUMMTTHHRREEAADDSS. * MMPP__UUNNSSEETTLLOOCCKK is the companion routine for MMPP__SSEETTLLOOCCKK. * MMPP__BBAARRRRIIEERR provides a simple interface to a single bbaarrrriieerr(3P). It can be used inside a parallel loop to force a barrier synchronization to occur among the parallel threads. The routine accepts no arguments, returns no value, and does not require any initialization. * MMPP__IINN__DDOOAACCRROOSSSS__LLOOOOPP determines whether or not execution is currently inside a parallel loop. This can be useful if you have an external routine that can be called both from inside a parallel loop and also from outside a parallel loop and if the routine must do different things depending on whether it is being called in parallel or not. * MMPP__SSEETT__SSLLAAVVEE__SSTTAACCKKSSIIZZEE specifies the stack _s_i_z_e (in bytes) to be used by the slave processes when they are created by sspprrooccsspp(2). The default size is 16MB. Note that slave processes only allocate their local data onto their stack. Shared data (even if allocated on the master's stack) is not counted. * MMPP__SSHHMMEEMM__GGEETT3322, MMPP__SSHHMMEEMM__PPUUTT3322, MMPP__SSHHMMEEMM__IIGGEETT3322, MMPP__SSHHMMEEMM__IIPPUUTT3322, MMPP__SSHHMMEEMM__GGEETT6644, MMPP__SSHHMMEEMM__PPUUTT6644, MMPP__SSHHMMEEMM__IIGGEETT6644, and MMPP__SSHHMMEEMM__IIPPUUTT6644 specify SHMEM-like operations. These routines allow you to manage communication explicitly, for reasons of performance or style, in a manner similar to SHMEM, one-sided communication, or message passing. The operations allow a thread to fetch from (get) and send to (put) data belonging to other threads. The MMPP__SSHHMMEEMM routines can be used with OpenMP directives and with the Silicon Graphics DDOOAACCRROOSSSS directives. These routines are identical to the original SHMEM routines, but they are prefixed by MMPP__. For information on the SHMEM routines, see the iinnttrroo__sshhmmeemm(3) man page or contact your sales representative. When using the MMPP__SSHHMMEEMM routines in a Fortran program, the data to be operated on must be in a common block and each thread must have its own private copy of the data being operated upon. If you are using OpenMP directives, use the TTHHRREEAADDPPRRIIVVAATTEE directive to declare the data to be private. If you are using the DDOOAACCRROOSSSS directive, declare the data to be private by specifying it as an argument to the --XXllooccaall option on the lldd(1) command. (These methods are equivalent to using the TTAASSKKCCOOMMMMOONN directive in a Fortran program on a UNICOS system.) A GGEETT routine requires that _s_o_u_r_c_e point to private data. A PPUUTT routine requires that _t_a_r_g_e_t point to private data. For more information on the OpenMP directives and the DDOOAACCRROOSSSS directive, see your compiler reference manuals. Note that the DDOOAACCRROOSSSS directive is outmoded; the preferred alternative is the OpenMP DDOO directive. These routines accept the following arguments: _t_a_r_g_e_t For the 32-bit versions of these routines, _t_a_r_g_e_t is a pointer to a 32-bit quantity. For the 64-bit versions of these routines, _t_a_r_g_e_t is a pointer to a 64-bit quantity. For a PPUUTT operation, _t_a_r_g_e_t must be private data. _s_o_u_r_c_e For the 32-bit versions of these routines, _t_a_r_g_e_t is a pointer to a 32-bit quantity. For the 64-bit versions of these routines, _t_a_r_g_e_t is a pointer to a 64-bit quantity. For a GGEETT operation, _s_o_u_r_c_e must be private data. _l_e_n_g_t_h Specifies the number of elements to be copied, in units of 32-bit or 64-bit elements, as appropriate. _s_o_u_r_c_e__t_h_r_e_a_d, _t_a_r_g_e_t__t_h_r_e_a_d Specify the numeric identifier of the remote source or target thread. _s_o_u_r_c_e__i_n_c, _t_a_r_g_e_t__i_n_c Specified for the strided routines, which are those with __IIGGEETT and __IIPPUUTT in their names. Specifies the increment, in units of 32-bit or 64-bit elements, along each of _s_o_u_r_c_e and _t_a_r_g_e_t, when performing the data transfer. The number of elements copied during a strided get or put operation is determined by _l_e_n_g_t_h. You can call the MMPP__SSHHMMEEMM routines only after the threads have been created, typically in the first DDOO/DDOOAACCRROOSSSS/PPAARRAALLLLEELL region. Performing these operations while the program is still serial leads to a runtime error because each thread's copy has not yet been created. As library routines, they incur some runtime overhead. DDIIRREECCTTIIVVEESS The MIPSpro Fortran 77 and MIPSpro 7 Fortran 90 compilers allow you to apply the capabilities of a Silicon Graphics multiprocessor computer to the execution of a single job. By coding a few simple directives, the compiler splits the job into concurrently executing pieces, thereby decreasing the wall-clock run time of the job. Directives enable, disable, or modify a feature of the compiler. Essentially, directives are command line options specified within the input file instead of on the command line. Unlike command line options, directives have no default setting. To invoke a directive, you must either toggle it on or set a desired value for its level. Directives placed on the first line of the input file are called _g_l_o_b_a_l _d_i_r_e_c_t_i_v_e_s. The compiler interprets them as if they appeared at the top of each program unit in the file. Use global directives to ensure that the program is compiled with the correct command line options. Directives appearing anywhere else in the file apply only until the end of the current program unit. The compiler resets the value of the directive to the global value at the start of the next program unit. You can set the global value using a command line option or a global directive. Some command line options act like global directives. Other command line options override directives. Many directives have corresponding command line options. If you specify conflicting settings in the command line and a directive, the compiler chooses the most restrictive setting. For Boolean options, if either the directive or the command line has the option turned off, it is considered off. For options that require a numeric value, the compiler uses the minimum of the command line setting and the directive setting. The Fortran compilers accept directives that generate code that can be run in parallel. The compiler directives look like Fortran comments. If multiprocessing is not turned on, these statements are treated as comments. This allows the identical source to be compiled with a single-processing compiler or by Fortran without the multiprocessing option. The following directives sets are supported for multiprocessing: * The OpenMP Fortran API directives. These portable, standard, multiprocessing directives are supported on IRIX and UNICOS systems. * The Origin series directives. These directives are developed specifically for the Origin series systems. * Other directive sets, including the PCF directives and the Autotasking directives, are supported for multiprocessing, but they are outmoded. For more information on any of the multiprocessing directives, see the _M_I_P_S_p_r_o _F_o_r_t_r_a_n _7_7 _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e or the _M_I_P_S_p_r_o _7 _F_o_r_t_r_a_n _9_0 _C_o_m_m_a_n_d_s _a_n_d _D_i_r_e_c_t_i_v_e_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. QQUUEERRYY IINNTTRRIINNSSIICCSS The DDSSMM(3I) man page describes several query intrinsics for distributed arrays. You can use these intrinsics to obtain information about an individual dimension of a distributed array CCOOMMMMAANNDD LLIINNEE SSUUPPPPOORRTT Various command line options must be in effect in order for multiprocessing to occur. The following command line options are used when multiprocessing is desired: * The --mmpp option enables all multiprocessing directives. * The --MMPP:: option selectively disables particular directive sets and controls other aspects of multiprocessing. This option must be specified in conjunction with the --mmpp option. For example, to disable the OpenMP directives, you would include both --mmpp and --MMPP::ooppeenn__mmpp==OOFFFF on your command line. For more information on these command line options, see the ff7777(1) or ff9900(1) man pages. EEXXAAMMPPLLEESS Example 1. In the following example, assume that the command line includes --WWll,,--XXllooccaall,,mmyyccoommmmoonn__, which ensures that each thread has a private copy of XX and YY: INTEGER X REAL(KIND=8), Y(100) COMMON /MYCOMMON/ X, Y Example 2. The following example copies the value of XX on thread 3 into the private copy of XX for the current thread: CALL MP_SHMEM_GET32 (X, X, 1, 3) Example 3. The following example copies the value of LLOOCCAALLVVAARR into the thread 5 copy of XX: CALL MP_SHMEM_PUT32 (X, LOCALVAR, 1, 5) Example 4. The following example fetches values from the thread 7 copy of array YY into LLOOCCAALLAARRRRAAYY: CALL MP_SHMEM_GET64 (LOCALARRAY, Y, 100, 7) Example 5. The following example copies the value of every other element of LLOOCCAALLAARRRRAAYY into the thread 9 copy of YY: CALL MP_SHMEM_IPUT64 (Y, LOCALARRAY, 2, 2, 50, 9) SSEEEE AALLSSOO ff7777(1), ff9900(1) bblloocckkpprroocc(2), eexxiitt(2), sspprrooccsspp(2), iinnttrroo__sshhmmeemm(3) DDSSMM(3I), SSYYNNCC(3I) bbaarrrriieerr(3P), uusssseettlloocckk(3P), ppee__eennvviirroonn(5) _M_I_P_S_p_r_o _F_o_r_t_r_a_n _7_7 _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e _M_I_P_S_p_r_o _7 _F_o_r_t_r_a_n _9_0 _C_o_m_m_a_n_d_s _a_n_d _D_i_r_e_c_t_i_v_e_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l This man page is available only online.